/*
 * @(#)StringConversion.java 1.0 2008/12/06
 */
package stardust.core.support.conversion;


import java.text.DateFormat;
import java.text.DecimalFormat;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Locale;


/**
 * <code>StringConversion</code> 类提供将日期、数字对象按格式转化为字符串。
 * <p/>
 * @see DateConversion
 * @version 1.0, 2008/12/06
 * @author ChenChang
 */
public class StringConversion
{

  /**
   * 将数字格式化为字符串，返回用匹配模式格式化后的字符串，匹配模式参考在如下说明：
   * <p>
   * # 数字占位符位，如果不足则不显示；<br />
   * 0 必须填充的数字占位符位，如果不足则在该位置补零；<br />
   * , 数字千位分隔符；<br />
   * . 小数点分隔符；<br />
   * ‰ 或 \u2030 千分号；<br />
   * % 百分号；<br />
   * ; 小数四舍五入分隔符；<br />
   * E 科学计数法符号；<br />
   * - 负号。
   * </p>
   * <p/>
   * @param number
 * 一个任意的数字类型，它可以是浮点型或整数。
   * @param pattern
* 匹配格式的表达式，参考匹配模式说明。
   * @param locale
 * 转换结果所面向的国家地区环境，这个参数为转换结果提供国际化支持，如果想采用系统默认值参考
   *          {@link #parseNumber(Number, String)} 方法或者通过
   *          {@link java.util.Locale#getDefault()} 方法直接取得系统默认值。
   * <p/>
   * @return 一个存储数字转换的结果的 {@link String} 对象。
   * <p/>
   * @see #parseNumber(Number, String)
   */
  public static String parseNumber(Number number, String pattern, Locale locale)
  {
    DecimalFormat decimalFormat = (DecimalFormat) DecimalFormat.getInstance(locale);

    decimalFormat.applyPattern(pattern);

    return decimalFormat.format(number);
  }

  /**
   * 将数字格式化为字符串，返回用匹配模式格式化后的字符串，此方法不对国家地区进行硬性控制使用系统默认值。<br />
   * 如果想对转换结果进行区域控制或了解相关匹配模式需参考{@link #parseNumber(Number, String, Locale)}方法。
   * <p/>
   * @param number
 * 一个任意的数字类型，它可以是浮点型或整数。
   * @param pattern
* 匹配格式的表达式，参考匹配模式说明。
   * <p/>
   * @return 一个存储数字转换的结果的 {@link String} 对象。
   * <p/>
   * @see #parseNumber(Number, String, Locale)
   */
  public static String parseNumber(Number number, String pattern)
  {
    return StringConversion.parseNumber(number, pattern, Locale.getDefault());
  }

  /**
   * 将时间对象转换为指定的格式，返回转换后的字符串，匹配模式参考下列说明：
   * <p>
   * <b>重复模式字符以使转换字符不足时补零。</b><br />
   * y 年<br />
   * M 年中的月份；<br />
   * d 月份中的天数；<br />
   * G Era标志符；<br />
   * w 年中的周数；<br />
   * W 月份中的周数；<br />
   * D 年中的天数；<br />
   * F 月份中的星期；<br />
   * E 星期中的天数；<br />
   * a Am/pm标记；<br />
   * H 一天中的小时数（0-23）；<br />
   * k 一天中的小时数（1-24）；<br />
   * K am/pm中的小时数（0-11）；<br />
   * h am/pm中的小时数（1-12）；<br />
   * m 小时中的分钟数（0～59）；<br />
   * s 分钟中的秒数（0～59）；<br />
   * S 毫秒数（0～999）；<br />
   * z 时区（General time zone Pacific Standard Time; PST; GMT-08:00）；<br />
   * Z 时区（RFC 822 time zone -0800）；<br />
   * MMM 月份的字符串表示；<br />
   * EEE 星期的字符串表示。<br />
   * </p>
   * <p/>
   * @param date
   * 一个需要转换的日期对象。
   * @param pattern
* 匹配格式的表达式，参考匹配模式说明。
   * @param locale
 * 转换结果所面向的国家地区环境，这个参数为转换结果提供国际化支持，如果想采用系统默认值参考
   *          {@link #parseDate(Number, String)} 方法或者通过
   *          {@link java.util.Locale#getDefault()} 方法直接取得系统默认值。
   * <p/>
   * @return 一个存储日期转换的结果的 {@link String} 对象。
   * <p/>
   * @see #parseDate(Date, String)
   */
  public static String parseDate(Date date, String pattern, Locale locale)
  {
    DateFormat dateFormat = new SimpleDateFormat(pattern, locale);

    return dateFormat.format(date);
  }

  /**
   * 将时间对象转换为指定的格式，返回转换后的字符串，此方法不对国家地区进行硬性控制使用系统默认值。<br />
   * 如果想对转换结果进行区域控制或了解相关匹配模式需参考{@link #parseNumber(Number, String, Locale)}方法。
   * <p/>
   * @param date
   * 一个需要转换的日期对象。
   * @param pattern
* 匹配格式的表达式，参考匹配模式说明。
   * <p/>
   * @return 一个存储日期转换的结果的 {@link String} 对象。
   * <p/>
   * @see #parseDate(Date, String)
   */
  public static String parseDate(Date date, String pattern)
  {
    return StringConversion.parseDate(date, pattern, Locale.getDefault());
  }

}
